class Model

Parent: Object

Class Index

Methods: abort_operation, active_entities, active_layer, active_layer=, active_view, add_note, attribute_dictionaries, attribute_dictionary, bounds, commit_operation, definitions, description, description=, entities, get_attribute, get_datum, guid, latlong_to_point, layers, list_datums, materials, modified?, options, pages, path, place_component, point_to_latlong, point_to_utm, raytest, rendering_options, save, save_thumbnail, select_tool, selection, set_attribute, set_datum, shadow_info, start_operation, title, utm_to_point, valid?

Sample Code: modeltests.rb

Instance Methods

abort_operation

The abort_operation method aborts the current operation started with the start_operation method.

Syntax:

status = model.abort_operation

Arguments:

Return Value:

status – true if successful, false if unsuccessful

Comments:

The abort_operation method is normally called from inside of a rescue clause to cancel an operation if something goes wrong.

Example:

status = model.abort_operation

active_entities

The active_entities method is used to retrieve an Entities object containing all of the entities in the active model or component (if you are within a component)

Syntax:

entities = model.active_entities

Arguments:

Return Value:

entities – an entities object

Comments:

Example:

model=Sketchup.active_model

entities=model.active_entities

active_layer

The active_layer method retrieves the active Layer.

Syntax:

layer = model.active_layer

Arguments:

Return Value:

layer – a layer object containing the currently active layer

Comments:

The default layer in SketchUp is layer 0.

Example:

active_layer =

The active_layer= method sets the active Layer object.

Syntax:

activelayer = model.active_layer=layer

Arguments:

layer – the layer object to be set as the active layer

Return Value:

activelayer – the newly set active layer object

Comments:

Example:

model = Sketchup.active_model
layers = model.layers
layers.add “My Layer”
activelayer = model.active_layer=layers[1]
layer=model.active_layer
name = layer.name

if (name != “My Layer”)
UI.messagebox “Failure: wrong Layer”
else
UI.messagebox name
end

active_view

The active_view method returns the active View object for this model.

Syntax:

view = model.active_view

Arguments:

Return Value:

view – a view object

Comments:

Example:

model = Sketchup.active_model
view = model.active_view

add_note

The add_note method is used to add a text note to the model.

Syntax:

note = Sketchup.active_model.add_note “note” x, y

Arguments:

“note” – a string note

x – a distance along the x axis between 0 and 1

y – a distance along the y axis between 0 and 1

Return Value:

note – a note object or an exception if it is unsuccessful.

Comments:

The position of the note is given as relative window positions between 0 and 1. For example, the following command would create a note that start one-tenth of the way down the screen from the upper left corner of the window.

Example:

model = Sketchup.active_model

begin
note = mode.add_note “Test Note”, 0.1, 0.1
rescue
UI.messagebox $!.message
end

attribute_dictionaries

The attribute_dictionaries method retrieves the AttributeDictionaries object that is associated with the Model.

Syntax:

attributedictionaries = model.attribute_dictionaries

Arguments:

Return Value:

attributedictionaries – an array of attribute dictionary if successful, nil if there are no attribute dictionaries

Comments:

Example:

model = Sketchup.active_model
attdicts = model.attribute_dictionaries

if (attdicts)
# code to do something if attribute dictionaries exist (usually you parse the array of
# dictionaries
else
# code to do something if attribute dictionaries do not exist
end

attribute_dictionary

The attribute_dictionary method retrieves an attribute dictionary with a given name that is associated with the model.

Syntax:

attributedictionary = model.attribute_dictionary “name” create

Arguments:

“name” – the name of the dictionary you are attempting to retrieve

create – (optional) if set to true an attribute dictionary of the given “name” will be created if not found

Return Value:

attributedictionary – an attribute dictionary object if successful, nil if unsuccessful

Comments:

The model and entities do not have attribute dictionaries by default. You must create model-related attribute dictionaries using the create flag.

Example:

bounds

The bounds method retrieves the bounding box of the model.

Syntax:

boundingbox = model.bounds

Arguments:

Return Value:

boundingbox = a bounding box for the model if successful

Comments:

Example:

model = Sketchup.bounds
bounds = model.bounds

if (bounds)
length = bounds.length
UI.messagebox length
else
UI.messagebox “Failure: No bounding box found”
end

commit_operation

The commit_operation method commits an operation for undo.

Syntax:

status = model.commit_operation

Arguments:

Return Value:

status – true if successful, false if unsuccessful

Comments:

The commit_operation method is normally called at the end of a method to commit the operation that the method performs.  

Example:

status = model.commit_operation

definitions

The definitions method retrieves a definition list containing all of the component definitions in the model.

Syntax:

definitionslist = model.definitions

Arguments:

Return Value:

definitions – a definitions list if successful.

Comments:

The returned definitions can be empty.

Example:

model = Sketchup.model
deflist = model.definitions
# parse array of definitions and act upon the definitions found

description

The description method retrieves a description of the model as found in the Model Info > Files panel.

Syntax:

description = model.description

Arguments:

Return Value:

description – a description if successful.

Comments:

The returned description can be empty. The default description for all models is empty.

Example:

model = Sketchup.model

desc = model.description

description=

The description= method sets the description of the model.

Syntax:

description = model.description “description”

Arguments:

“description” – (optional) the description string to be set.

Return Value:

description – the currently set description string.

Comments:

If you do not include a description string, the description is cleared and an empty description is returned.

Example:

model = Sketchup.model

description = model.description=”This is a model of a house on the North West Corner of 10th and Dolores Street in Carmel, California”

entities

The entities method returns an Entities object containing an array of entities in the model.

Syntax:

entities = model.entities

Arguments:

Return Value:

entities – an Entities object if successful

Comments:

If no entities are in your model, this method returns an empty Entities object (an empty array)

Example:

model = Sketchup.model
entities = model.entities

# Add a group to the entities in the model
entities = entities.addgroup

get_attribute

The get_attribute method gets the value of an attribute that in the AttributeDictionary with the given name.

Syntax:

value = model.get_attribute “dictionaryname”, key, defaultvalue

Arguments:

“dictionaryname” – the name of the dictionary containing the value

“key” – the key containing the value

defaultvalue – (optional) default value that will be returned if a value does not exist

Return Value:

value – the value for a given key in the given dictionary if a value exists; the default value if a defaultvalue is provided and the value does not exist; nil if the value does not exist and no defaultvalue is provided.

Comments:

Example:

get_datum

the get_datum method retrieves the datum, in the form of a string, used in UTM conversions.

Syntax:

datum = model.get_datum

Arguments:

Return Value:

datum – a datum represented as a string if successful.

Comments:

Example:

model = Sketchup.active_model

datum = model.get_datum

guid

The guid method retrieves the globally unique identifier, in the form of a string, for the Model.

Syntax:

guid = model.guid

Arguments:

Return Value:

guid – a globally unique identifier, in the form of a string, for the model

Comments:

Example:

model = Sketchup.active_model

guid = model.guid

latlong_to_point

The latlong_to_point method convert a latitude and longitude to a Point3d object in the model.

Syntax:

point = model.latlong_to_point latlong

Arguments:

latlong – a latlong object

Return Value:

point – a point3d object if successful, false if unsuccessful.

Comments:

Example:

latitude = [40.01700, 105.28300]
model = Sketchup.active_model

begin
latlong = Geom::LatLong.new(latitude)
rescue
UI.messagebox $!.message
end

point = model.latlong_to_point latlong

layers

The layers method retrieves a collection of all Layers objects in the model.

Syntax:

layers = model.layers

Arguments:

Return Value:

layers – a Layers object containing a collection of Layers in the model

Comments:

Example:

model = Sketchup.active_model

layers = model.layers

list_datums

This method retrieves an Array of all of the datums recognized by SketchUp.

Syntax:

datums = model.list_datums

Arguments:

Return Value:

datums – An Array object containing the datums supported by SketchUp

Comments:

Example:

model = Sketchup.active_model
datums = model.list_datums

if (datums)
# display a paragraph with all of the datums
UI.messagebox datums
end

materials

The materials method returns a collection of all of the Materials in the model.

Syntax:

materials = model.materials

Arguments:

Return Value:

Comments:

Example:

model = Sketchup.active_model
materials = model.materials

if (materials)
# List number of materials
count = materials.count
UI.messagebox count
end

modified?

The modified? method determines if the Model has been modified since the last save.

Syntax:

status = model.modified?

Arguments:

Return Value:

status = true if the model has been modified since last save (and requires a save), false if the model has not been modified.

Comments:

Example:

model = Sketchup.active_model
entities = model.active_entities

# Add a group to force the status return value to be true
entities.add_group
status = model.modified?

if (status)
# If status is true, the following message is displayed
UI.messagebox “You better save soon.”
end

options

The options method retrieves the options manager that defines the options settings for the model.

Syntax:

optionsmanager = model.options

Arguments:

Return Value:

optionsmanager – an OptionsManager object containing one or more options providers if successful.

Comments:

There are 5 default options managers. These are: PageOptions, AxisOptions, SlideshowOptions, UnitsOptions, and NamedOptions.

Example:

model = Sketchup.active_model
optionsmanager = model.options

if (optionsmanager)
# If an options manager is returned, iterate through each option provider within the                  
# options
# options manager and display its name.
size = optionsmanager.size
UI.messagebox size
for option in optionsmanager
option = optionsmanager[x]
name = optionsmanager.name
UI.messagebox name
x = x + 1
end
else
UI.messagebox “Failure”
end

pages

The pages method retrieves a Pages object containing all of the pages in the Model.

Syntax:

pages = model.pages

Arguments:

Return Value:

pages – returns a Pages object with 0 or more pages.

Comments:

Example:

model = Sketchup.model
pages = model.pages
# Add a page to the Pages object
page = pages.add
size = pages.size
# Size should be 1
UI.messagebox size

path

The path method retrieves the path of the file from which the model was opened.

Syntax:

path = model.path

Arguments:

Return Value:

path – an string containing the path for the currently opened model.

Comments:

An empty string is returned for a new model (one which has not been saved and opened)

Example:

model = Sketchup.model
# Return the current path (empty)
path = model.path
UI.messagebox path

place_component

The place_component method places a new component in the Model using the component placement tool.

The first argument is a ComponentDefinition. There is a second optional argument. If it is true, it says to stay in the tool and place multiple instances of the component.

Syntax:

status = model.placecomponent componentdefinition, repeat

Arguments:

componentdefinition – A component definition object containing the definition (blueprint) for the component

repeat – if set to true, stay in the component placement tool and place multiple components

Return Value:

Comments:

Example:

point_to_latlong

The point_to_latlong method converts a point in the model to a LatLong so that you can get its latitude and longitude.

Syntax:

latlong = model.point_to_latlong point

Arguments:

point – a Point3d object

Return Value:

latlong – a LatLong object

Comments:

This method uses the location information set in ShadowInfo.

Example:

coordinates = [10,10,10]
model = Sketchup.active_model
begin
point = Geom::Point3d.new(coordinates)
rescue
UI.messagebox $!.message
end

latlong = model.point_to_latlong(point)

if (latlong)
# if a latlong object was returned, convert contents to a string
latlongvalue = latlong.to_s
UI.messagebox latlongvalue
else
UI.messagebox “Failure”
end

point_to_utm

This method converts a Point3d object in the Model to UTM coordinates.

Syntax:

utm = model.point_to_utm(point)

Arguments:

point – A Point3d object

Return Value:

utm – a UTM object

Comments:

This method uses the location information set in ShadowInfo. See also UTM.

Example:

coordinates = [10,10,10]
model = Sketchup.active_model

begin
point = Geom::Point3d.new(coordinates)
rescue
UI.messagebox $!.message
end

utm = model.point_to_utm(point)
if (utm)
# if a utm object was returned, convert contents to a string
utmvalue = utm.to_s
UI.messagebox utmvalue
else
UI.messagebox “Failure”
end

raytest

Cast a ray through the model and return the first thing that it hits.

Syntax:

Arguments:

Return Value:

Comments:

Example:

rendering_options

The rendering_options method retrieves the RenderingOptions object for this Model.

Syntax:

renderingoptions = model.rendering_options

Arguments:

Return Value:

renderingoptions – a RenderingOptions object

Comments:

Example:

save

This method is used to save the model to a file.

Syntax:

status = model.save “filename”

Arguments:

“filename” – the name of the file to save

Return Value:

status – true if successful, false if unsuccessful

Comments:

Example:

model = SketchUp.active_model
status = model.save “mysketchup.skp”

save_thumbnail

The save_thumbnail method is used to save a thumbnail image to a file.

Syntax:

status = model.save_thumbnail "filename"

Arguments:

"filename" - the name of the file, with extension, to save the thumbnail as

Return Value:

status - true if successful, false if unsuccessful

Comments:

Returns nil if it is an internal component.

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = model.save_thumbnail "testthumbnail2.jpg"
UI.messagebox status

select_tool

This method is used to select a SketchUp Tool object  as the active tool. You must implement the SketchUp Tool interface to create a tool prior to calling this method.

Syntax:

tool = model.select_tool tool

Arguments:

tool – the Tool object you want to select.

Return Value:

tool – A Tool object.

Comments:

The select tool is returned if you pass nil to the select_tool method. You must implement the SketchUp Tool interface to create a tool, prior to calling this method, and then instance the tool implementation and pass the object to this method.

Example:

model = Sketchup.active_model
tool = model.select_tool nil

selection

This method retrieves a  Selection object for the model, containing the currently selected entities.

Syntax:

selection = model.selection

Arguments:

Return Value:

selection – A Selection object with 0 or more entities that are currently selected.

Comments:

Example:

model = Sketchup.active_model
selection = model.selection

set_attribute

This method is used to set the value of an attribute in an attribute dictionary with the given name.

Syntax:

value = model.set_attribute “attributedictionaryname”, “key”, “value”

Arguments:

“attributedictionaryname” – the name of the attribute dictionary whose attribute you wish to set

“key” – the attribute name

“value” – the value to set

Return Value:

value – the value that was set

Comments:

This method can be used create a new AttributeDictionary object, if needed.

Example:

model = Sketchup.active_model

value = model.set_attribute “testdictionary” “test” “115”

set_datum

This method sets the datum used in conversions between the internal coordinate system and UTM.

Syntax:

value = model.setdatum "datum"

Arguments:

Return Value:

Comments:

The default datum is WGS84. You can use the method list_datums to get a list of all of the datums supported in SketchUp. If you pass an invalid datum to set_datum, set_datum returns the default datum.

Example:

model = Sketchup.active_model

value = model.set_datum “Adindan”

shadow_info

This method is used to retrieve the shadow information for the Model.

Syntax:

shadowinfo = model.shadow_info

Arguments:

Return Value:

shadowinfo – a ShadowInfo object.

Comments:

Example:

model = Sketchup.active_model

shadowinfo = model.shadow_info

start_operation

The start_operation method is used to  notify Edit > Undo that a new operation (which can be undone) is starting.

Syntax:

status = model.start_operation

Arguments:

Return Value:

status – true if successful, false if unsuccessful

Comments:

The String is a description for the operation that is displayed adjacent to the Edit > Undo menu item.

Example:

status = model.start_operation

title

The tile method retrieves the name of the model.

Syntax:

title = model.title

Arguments:

Return Value:

title – the title of the model or an empty string (if the title is not set)

Comments:

Example:

model = Sketchup.active_model

title = model.title

utm_to_point

The utm_to_point method converts a position given in UTM coordinates to a Point3d in the Model.

Syntax:

point = model.utm_to_point utm

Arguments:

utm – a UTM object.

Return Value:

point - A Point3d object.

Comments:

Example:

point = [10,10,10]
model = Sketchup.active_model
begin
point = Geom::Point3d.new(point)
rescue
UI.mesagebox $!.message
end

# Create a UTM object from the point
utm = model.point_to_utm point
# Pass that UTM object right back into utm_to_point to get the UTM back again
point = model.utm_to_point utm

if (point)
pointvalue = point.to_s
UI.messagebox pointvalue
else
UI.messagebox “Failure”
end

valid?

The valid method determines if the model is valid.

Syntax:

status = model.valid?

Arguments:

Return Value:

status – true if the model is valid, false if it is invalid.

Comments:

Example:

model = Sketchup.active_model

valid = model.valid?